.env.unified.lan (3)

7-8: Fix placeholder values and trailing whitespace.

Line 8 has trailing whitespace and both lines should have quoted values per dotenv standards.

Apply this diff to fix formatting issues:

-SUPABASE_URL=your database link
-SUPABASE_SERVICE_KEY=Your Key 
+SUPABASE_URL="your database link"
+SUPABASE_SERVICE_KEY="Your Key"

---

20-24: Domain name inconsistencies in configuration.

There are inconsistencies in domain name capitalization and format across the configuration:

• Line 20: archon.YourDomainName.com
• Line 22: archon.yourdomain.com
• Line 24: archon.yourdomain.com
• Line 29: archon.yourdomainname.com

Apply this diff to standardize domain names:

-HOST=archon.YourDomainName.com
+HOST="archon.yourdomain.com"
-CORS_ORIGINS=https://archon.yourdomain.com
+CORS_ORIGINS="https://archon.yourdomain.com"
-API_BASE_URL=https://archon.yourdomain.com/api
+API_BASE_URL="https://archon.yourdomain.com/api"
-VITE_API_URL=https://archon.yourdomain.com
+VITE_API_URL="https://archon.yourdomain.com"
-VITE_MCP_HOST=archon.yourdomainname.com
+VITE_MCP_HOST="archon.yourdomain.com"

---

64-64: Add missing newline at end of file.

The file is missing a newline at the end, which is a standard convention.

Add a newline at the end of the file.

.env.example (1)

30-31: Remove unnecessary blank lines.

The double blank lines are not needed and violate dotenv formatting conventions.

Apply this diff to remove extra blank lines:

-

-
###################################################################

.env.unified.local (6)

38-38: Remove extra blank line flagged by dotenv-linter.

-

---

42-54: Satisfy dotenv-linter key ordering within this section.

Reorder as suggested by linter to avoid warnings.

-DEPLOYMENT_MODE=local
-BUILD_TARGET=development
+BUILD_TARGET=development
+DEPLOYMENT_MODE=local
 NODE_ENV=development
@@
-HOST=localhost
-BIND_IP=127.0.0.1
-CORS_ORIGINS=http://localhost:3737
-API_BASE_URL=http://localhost:8181
-VITE_API_URL=http://localhost:8181
+API_BASE_URL=http://localhost:8181
+BIND_IP=127.0.0.1
+CORS_ORIGINS=http://localhost:3737
+HOST=localhost
+VITE_API_URL=http://localhost:8181

---

58-62: Reorder MCP keys to satisfy linter (port before protocol).

 VITE_MCP_HOST=localhost
-VITE_MCP_PROTOCOL=http
 VITE_MCP_USE_PROXY=false
-VITE_MCP_PORT=8051
+VITE_MCP_PORT=8051
+VITE_MCP_PROTOCOL=http

---

66-70: Reorder service ports per linter suggestions.

-ARCHON_SERVER_PORT=8181
-ARCHON_MCP_PORT=8051
-ARCHON_AGENTS_PORT=8052
-ARCHON_UI_PORT=3737
+ARCHON_AGENTS_PORT=8052
+ARCHON_MCP_PORT=8051
+ARCHON_SERVER_PORT=8181
+ARCHON_UI_PORT=3737

---

74-78: Reorder dev feature keys per linter (profiles before socket).

-DOCKER_SOCKET=/var/run/docker.sock
-PROD=false
-# Use dev profile for development with volume mounts
-COMPOSE_PROFILES=dev
+PROD=false
+# Use dev profile for development with volume mounts
+COMPOSE_PROFILES=dev
+DOCKER_SOCKET=/var/run/docker.sock

---

89-92: Reorder optional keys per linter and add minor CORS tip.

• Reorder to place LOGFIRE_TOKEN/LOG_LEVEL before OPENAI_API_KEY.
• Consider adding 127.0.0.1 to CORS for local setups using that hostname.

-AGENTS_ENABLED=false
-OPENAI_API_KEY=
-LOGFIRE_TOKEN=
-LOG_LEVEL=INFO
+AGENTS_ENABLED=false
+LOGFIRE_TOKEN=
+LOG_LEVEL=INFO
+OPENAI_API_KEY=

If needed:

- CORS_ORIGINS=http://localhost:3737
+ CORS_ORIGINS=http://localhost:3737,http://127.0.0.1:3737

archon-ui-main/src/services/credentialsService.ts (2)

79-85: Add retry with exponential backoff for external calls.

Guidelines require retries and clear failures. Introduce a small helper and use it here.

 class CredentialsService {
+  private async request(input: RequestInfo, init: RequestInit | undefined, context: string, attempts = 3, baseDelayMs = 300): Promise<Response> {
+    let lastErr: any;
+    for (let i = 0; i < attempts; i++) {
+      try {
+        const res = await fetch(input, init);
+        if (!res.ok && res.status >= 500 && res.status < 600) throw new Error(`HTTP ${res.status}`);
+        return res;
+      } catch (err) {
+        lastErr = err;
+        if (i < attempts - 1) await new Promise(r => setTimeout(r, baseDelayMs * Math.pow(2, i)));
+      }
+    }
+    throw this.handleCredentialError(lastErr, context);
+  }
@@
   async getAllCredentials(): Promise<Credential[]> {
-    const response = await fetch(`${this.baseUrl}/api/credentials`);
-    if (!response.ok) {
-      throw new Error("Failed to fetch credentials");
-    }
+    const response = await this.request(`${this.baseUrl}/api/credentials`, undefined, "Fetching credentials");
+    if (!response.ok) throw new Error(`Failed to fetch credentials: HTTP ${response.status}`);
     return response.json();
   }

Follow-up: adopt request() in other methods for consistency.

---

130-137: Include status text in single-credential failure.

More actionable context helps debugging.

-      throw new Error(`Failed to fetch credential: ${key}`);
+      throw new Error(`Failed to fetch credential '${key}': HTTP ${response.status} ${response.statusText}`);

archon-ui-main/src/components/settings/FeaturesSection.tsx (3)

25-26: Rename loading → isLoading to meet state naming guideline.

Consistent with “is[Action]ing” convention.

-  const [loading, setLoading] = useState(true);
+  const [isLoading, setIsLoading] = useState(true);
@@
-    if (loading) return;
+    if (isLoading) return;
@@
-      setLoading(true);
+      setIsLoading(true);
@@
-      setLoading(false);
+      setIsLoading(false);
@@
-                disabled={loading || !projectsSchemaValid}
+                disabled={isLoading || !projectsSchemaValid}
@@
-                disabled={loading}
+                disabled={isLoading}

Apply the same rename in other handlers.

Also applies to: 109-111, 136-136, 167-168, 236-237, 312-313

---

94-103: Add actionable context to errors surfaced to users.

Include attempted URL and basic advice.

-      console.error('Failed to load settings:', error);
+      console.error('Failed to load settings (GET /api/projects/health, credentials):', error);
@@
-      setProjectsSchemaError('Failed to load settings');
+      setProjectsSchemaError('Failed to load settings. Verify backend is reachable at /api and database connectivity.')

---

34-44: Consider polling hook for projects health.

If you want live schema/health reflection, wrap the health fetch with the provided polling hook and backoff.

archon-ui-main/src/config/api.ts (1)

24-39: Tighten env handling and reduce noisy logs.

• Vite env vars are strings or undefined; drop null check.
• Gate console.info to DEV only.

-  const portEnv = import.meta.env.VITE_ARCHON_SERVER_PORT;
+  const portEnv = import.meta.env.VITE_ARCHON_SERVER_PORT as string | undefined;
@@
-  if (portEnv === undefined) {
+  if (portEnv === undefined) {
     // No port env var at all - use default for local dev
-    console.info('[Archon] Using default ARCHON_SERVER_PORT: 8181');
+    if (import.meta.env.DEV) console.info('[Archon] Using default ARCHON_SERVER_PORT: 8181');
     return `${protocol}//${host}:8181`;
-  } else if (portEnv === '' || portEnv === null) {
+  } else if (portEnv === '') {
     // Port explicitly set to empty - don't add port (for LAN/proxy setups)
-    console.info('[Archon] No port specified - using domain only');
+    if (import.meta.env.DEV) console.info('[Archon] No port specified - using domain only');
     return `${protocol}//${host}`;
   } else {
     // Port is defined with a value - use it
     return `${protocol}//${host}:${portEnv}`;
   }

archon-ui-main/Dockerfile (1)

53-59: Prefer not installing global binaries; use npx or a slimmer static server.

Smaller attack surface and image size.

-RUN npm install -g serve
-EXPOSE 3737
-CMD ["serve", "-s", "dist", "-l", "3737"]
+EXPOSE 3737
+# Option A: use npx
+CMD ["npx", "serve", "-s", "dist", "-l", "3737"]
+# Option B (lean): copy dist into nginx:alpine stage and serve via nginx

archon-ui-main/src/config/mcp.ts (2)

29-33: Harden parsing and typing for envs (guard NaN port, narrow protocol type).

Prevents NaN and clarifies allowed protocols.

-export function getMCPConfig(): MCPConfig {
-  const host = import.meta.env.VITE_MCP_HOST || 'localhost';
-  const protocol = import.meta.env.VITE_MCP_PROTOCOL || 'http';
-  const useProxy = import.meta.env.VITE_MCP_USE_PROXY === 'true';
-  const port = import.meta.env.VITE_MCP_PORT || '8051';
+type Protocol = 'http' | 'https';
+
+export function getMCPConfig(): MCPConfig {
+  const host = import.meta.env.VITE_MCP_HOST || 'localhost';
+  const protocol = (import.meta.env.VITE_MCP_PROTOCOL || 'http') as Protocol;
+  const useProxy = String(import.meta.env.VITE_MCP_USE_PROXY) === 'true';
+  const portStr = import.meta.env.VITE_MCP_PORT ?? '8051';
+  const parsedPort = Number.parseInt(String(portStr), 10);
+  const port = Number.isFinite(parsedPort) ? parsedPort : 8051;
@@
-  return {
-    host,
-    port: parseInt(port),
+  return {
+    host,
+    port,
     protocol,
     useProxy,
     url,
     transport: 'sse'
   };

Also applies to: 40-47

---

73-75: Reuse computed config for LAN check.

Avoids duplicated parsing logic.

-export function isLANDeployment(): boolean {
-  return import.meta.env.VITE_MCP_USE_PROXY === 'true';
-}
+export function isLANDeployment(): boolean {
+  return getMCPConfig().useProxy;
+}

README.md (2)

82-83: Use the same unified compose command for upgrade too (consistency).

-docker compose -f docker-compose.unified.yml up --build -d
+docker compose -f docker-compose.unified.yml up -d --build

-docker compose -f docker-compose.unified.yml up -d --build
+docker compose -f docker-compose.unified.yml up -d --build

Also applies to: 211-212

---

483-572: Nice LAN section; add caution on Traefik dashboard exposure and DNS creds.

Warn that dashboard must be protected and Cloudflare tokens scoped minimally.

docker-compose.unified.yml (2)

171-171: Duplicate container_name “archon-ui” across dev/prod services can collide.

Drop container_name or make them unique per profile.

-    container_name: archon-ui
+    # container_name intentionally omitted to avoid collisions across profiles

Also applies to: 221-221

---

259-260: Add trailing newline to satisfy linters.

python/src/server/main.py (2)

169-175: Trim CORS origins when splitting to avoid whitespace mismatches.

-config = get_config()
-cors_origins = config.cors_origins.split(",") if config.cors_origins else ["http://localhost:3737"]
+config = get_config()
+cors_origins = (
+    [o.strip() for o in config.cors_origins.split(",") if o.strip()]
+    if config.cors_origins
+    else ["http://localhost:3737"]
+)

---

34-34: Duplicate import of get_config.

Keep one import at module top.

-# Import Logfire configuration
-from .config.config import get_config
+# Import Logfire configuration
+# get_config imported once at module scope
@@
-        from .config.config import get_config
-
-        get_config()  # This will raise ConfigurationError if anon key detected
+        get_config()  # Validates configuration; raises on misconfig

Also applies to: 76-79

python/src/server/config/config.py (1)

203-207: Validate port range (1–65535) and fail fast with clear error.

     try:
-        port = int(port_str)
+        port = int(port_str)
+        if not (1 <= port <= 65535):
+            raise ValueError("out of range")
     except ValueError as e:
-        raise ConfigurationError(f"PORT must be a valid integer, got: {port_str}") from e
+        raise ConfigurationError(f"PORT must be an integer between 1 and 65535, got: {port_str}") from e

Also applies to: 214-224

traefik/data/traefik.yml (3)

1-3: Disable debug in production.

Avoid verbose logs and potential information leakage.

 api:
   dashboard: true
-  debug: true
+  debug: false

---

23-35: ACME/Cloudflare placeholders: document required env vars and protect dashboard.

Ensure CF token (Zone.DNS edit) is scoped least-privilege and Traefik dashboard isn’t publicly routed.

---

35-35: Add trailing newline to satisfy linters.

python/src/server/config/service_discovery.py (3)

108-119: Clarify MCP proxy host/protocol and avoid reusing the protocol param.

Prefer an explicit MCP host if provided and avoid shadowing the function arg. This also aligns with frontend helpers expecting VITE_MCP_HOST/PROTOCOL.

-            if service == "mcp" and os.getenv("VITE_MCP_USE_PROXY", "false").lower() == "true":
-                # Use external host and protocol for proxy mode
-                external_host = os.getenv("HOST", "localhost")
-                external_protocol = os.getenv("VITE_MCP_PROTOCOL", protocol)
-                url = f"{external_protocol}://{external_host}:{port}"
+            if service == "mcp" and os.getenv("VITE_MCP_USE_PROXY", "false").lower() == "true":
+                # Prefer explicit MCP host, then HOST
+                external_host = os.getenv("VITE_MCP_HOST") or os.getenv("HOST", "localhost")
+                effective_protocol = os.getenv("VITE_MCP_PROTOCOL", protocol)
+                url = f"{effective_protocol}://{external_host}:{port}"

---

122-128: Don’t mutate input parameter; compute an effective_protocol for MCP.

Prevents cache key and readability pitfalls.

-            # For MCP in local mode, respect the protocol setting
-            if service == "mcp":
-                protocol = os.getenv("VITE_MCP_PROTOCOL", protocol)
-            url = f"{protocol}://{host}:{port}"
+            # For MCP in local mode, respect the protocol setting
+            effective_protocol = os.getenv("VITE_MCP_PROTOCOL", protocol) if service == "mcp" else protocol
+            url = f"{effective_protocol}://{host}:{port}"

---

95-98: Cache key can become stale when protocol is overridden. Defer cache until URL is finalized.

Current key uses the pre-override protocol. Cache by the final URL to avoid subtle mismatches.

-        cache_key = f"{protocol}://{service}"
-        if cache_key in self._cache:
-            return self._cache[cache_key]
+        # Defer cache lookup until URL is fully resolved

-        self._cache[cache_key] = url
-        return url
+        cache_key = url
+        cached = self._cache.get(cache_key)
+        if cached:
+            return cached
+        self._cache[cache_key] = url
+        return url

Also applies to: 129-131

docs/prd.md (2)

20-23: Fix markdown table spacing (lint MD058).

Add blank lines around the table to satisfy markdownlint.

-### Change Log
-| Date | Version | Description | Author |
+### Change Log
+
+| Date | Version | Description | Author |
 |------|---------|-------------|---------|
 | 2025-01-09 | 1.0 | Initial PRD creation based on Mary's analysis | John (PM) |
+

---

36-36: Address bare URLs and emphasis lint warnings (MD034, MD037, MD036).

Wrap bare URLs in angle brackets and avoid spaces inside emphasis markers; convert emphasized headings to real headings.

Would you like a quick follow-up PR to auto-fix these with markdownlint --fix?

Also applies to: 186-186

README-TRAEFIK.md (1)

118-133: Restrict dashboard exposure with IP allowlist in addition to Basic Auth.

Defense-in-depth for admin surface.

-      - "traefik.http.routers.traefik-secure.middlewares=traefik-auth"
+      - "traefik.http.middlewares.lan-whitelist.ipwhitelist.sourcerange=10.0.0.0/8,192.168.0.0/16,172.16.0.0/12"
+      - "traefik.http.routers.traefik-secure.middlewares=traefik-auth,lan-whitelist"

traefik/docker-compose.yml (1)

29-43: Whitelist LAN for dashboard router.

Add IP allowlist to reduce exposure.

-      - traefik.http.routers.traefik-secure.middlewares=traefik-auth
+      - traefik.http.middlewares.lan-whitelist.ipwhitelist.sourcerange=10.0.0.0/8,192.168.0.0/16,172.16.0.0/12
+      - traefik.http.routers.traefik-secure.middlewares=traefik-auth,lan-whitelist

README-LAN.md (2)

22-26: Unify domain and casing in quick start output.

Use the same domain as prerequisites to avoid confusion.

-# Access at: https://archon.yourDomain.com
+# Access at: https://archon.mcdonaldhomelab.com

---

49-56: Add language to fenced diagram block (MD040).

Improves rendering and lints clean.

-```
+```text
 Internet → Traefik Proxy → Docker Networks
                         ├── archon-frontend:3737 (/)
                         ├── archon-server:8181 (/api/*)  
                         └── Internal Services
                             ├── archon-mcp:8051
                             └── archon-agents:8052

</blockquote></details>
<details>
<summary>traefik/data/config.yml (1)</summary><blockquote>

`91-97`: **Fix YAML indentation and ensure newline at EOF.**

Lint errors indicate wrong nesting and missing newline.



```diff
-    default-whitelist:
-      ipAllowList:
-        sourceRange:
-        - "10.0.0.0/8"
-        - "192.168.0.0/16"
-        - "172.16.0.0/12"
+    default-whitelist:
+      ipAllowList:
+        sourceRange:
+          - "10.0.0.0/8"
+          - "192.168.0.0/16"
+          - "172.16.0.0/12"
@@
-        - default-whitelist
-        - default-headers
+          - default-whitelist
+          - default-headers

Ensure the file ends with a single newline.

Also applies to: 101-102

.gitignore (1)

8-9: Clarify ignore scope for new entries

Without a leading slash, these patterns match anywhere in the repo. If you intend to ignore only top-level entries, prefix with "/". Also confirm you really want to exclude LAN migration docs from version control.

Apply if root-only is desired:

-.bmad-core
-lan-migration-docs/
+/.bmad-core
+/lan-migration-docs/

python/pyproject.toml (2)

182-182: Global mypy ignore_missing_imports may hide issues

Keeping this true is fine for untyped third-party libs, but consider scoping it to specific packages to avoid masking real problems in first-party code.

Example override (add alongside current config):

[tool.mypy.overrides]
module = [
  "supabase.*",
  "crawl4ai.*",
  "logfire.*",
]
ignore_missing_imports = true

---

8-11: Align python-jose extra and httpx versions across base and groups

Add the [cryptography] extra to the base python-jose and bump all group httpx deps (now >=0.24.0) to >=0.28.1 and group python-jose[cryptography] deps (now >=3.3.0) to >=3.5.0.

Minimal base tweak:

 dependencies = [
-    "httpx>=0.28.1",
-    "python-jose>=3.5.0",
+    "httpx>=0.28.1",
+    "python-jose[cryptography]>=3.5.0",
 ]

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-06T20:04:08.138Z
Learning: Applies to .env : Require SUPABASE_URL and SUPABASE_SERVICE_KEY in .env; optional LOGFIRE_TOKEN, LOG_LEVEL, ARCHON_*_PORT variables

Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-06T20:05:27.092Z
Learning: Applies to archon-ui-main/src/features/**/*.{ts,tsx} : Use vertical slice structure: each feature owns its components/hooks/types/services; nest sub-features by domain

Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-06T20:05:27.092Z
Learning: Applies to archon-ui-main/src/features/**/*.{ts,tsx} : Use TanStack Query for all data fetching in /features (no manual fetch chains in components)

Learnt from: stevepresley
PR: coleam00/Archon#573
File: archon-ui-main/src/config/api.ts:15-25
Timestamp: 2025-09-04T16:30:05.227Z
Learning: Archon UI API config: Prefer lazy getters getApiFullUrl() and getWsUrl() over module-load constants to avoid SSR/test crashes. Avoid CommonJS exports patterns (Object.defineProperty(exports,…)) in ESM. Add typeof window guards with VITE_API_URL fallback inside getApiUrl()/getWebSocketUrl() when SSR safety is required.

UNIFIED-DEPLOYMENT.md (4)

16-16: Standardize on Docker Compose V2 CLI ("docker compose").

Use consistent, modern syntax across docs.

-docker-compose -f docker-compose.unified.yml up -d
+docker compose -f docker-compose.unified.yml up -d

-docker-compose down
-docker-compose -f docker-compose.unified.yml up -d
+docker compose down
+docker compose -f docker-compose.unified.yml up -d

-docker network create proxy
+docker network create proxy
 # (no change, just ensure subsequent commands use `docker compose`)

Also applies to: 30-30, 89-91, 98-106

---

50-55: Document required environment variables (Supabase).

Make required vars explicit per setup expectations.

 ### Core Settings
 - `HOST`: Domain name or localhost (used for service discovery)
 - `BIND_IP`: IP to bind ports to (`127.0.0.1` for local, `0.0.0.0` for LAN, empty for all interfaces)
 - `CORS_ORIGINS`: Comma-separated list of allowed CORS origins
 - `API_BASE_URL`: Base URL for API service
+ - `SUPABASE_URL`: Your Supabase project URL
+ - `SUPABASE_SERVICE_KEY`: Supabase service role key (legacy, longer key)

---

63-67: Clarify recommended VITE_MCP_ values by mode.*

This doc says “usually false” for VITE_MCP_USE_PROXY, while README sets it to true for LAN. Pick one guidance and note per-mode defaults.

-`VITE_MCP_USE_PROXY`: Whether to proxy MCP through frontend (usually `false`)
+`VITE_MCP_USE_PROXY`: Whether the frontend proxies MCP
+  - Local: `false` (direct `localhost:8051`)
+  - LAN/Prod (behind Traefik): `true` (route `/mcp` via proxy)

---

122-129: Emphasize not publishing service ports when fronted by Traefik.

Reduce attack surface in LAN/Prod by removing host port publishes and relying on proxy/network-only access.

• In LAN/Prod, do not map 8181/8051/8052 to the host; attach services to ${PROXY_NETWORK} and expose via Traefik only.

README-LAN.md (4)

23-23: Use Docker Compose V2 syntax consistently.

-docker-compose -f docker-compose.unified.yml up -d
+docker compose -f docker-compose.unified.yml up -d

-# Review Docker Compose logs: `docker-compose -f docker-compose.unified.yml logs -f`
-# Check service health: `docker-compose -f docker-compose.unified.yml ps`
+# Review Docker Compose logs: `docker compose -f docker-compose.unified.yml logs -f`
+# Check service health: `docker compose -f docker-compose.unified.yml ps`

Also applies to: 117-119

---

57-63: Add language to fenced block (markdownlint MD040).

-```
+```text
 Internet → Traefik Proxy → Docker Networks
                         ├── archon-frontend:3737 (/)
                         ├── archon-server:8181 (/api/*)  
                         ├── archon-mcp:8051 (exposed for AI IDEs)
                         └── archon-agents:8052 (optional, when enabled)

---

`31-37`: **Clarify exposure: prefer Traefik-only in LAN/Prod.**

When using Traefik, avoid publishing service ports to the host; route via Traefik and keep containers on the proxy network only.



- Remove host port publishes for 3737/8181/8051/8052 in LAN/Prod profile.
- Add Traefik routers for `/`, `/api`, `/mcp` (or subdomains) with TLS.


Also applies to: 41-47

---

`10-10`: **Unify placeholder casing for domain.**


```diff
-archon.yourDomain.com
+archon.yourdomain.com

Also applies to: 25-26, 32-33, 84-89, 105-106

README.md (5)

254-281: Add language to the ASCII diagram block (markdownlint MD040).

-```
+```text
 ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
 │   Frontend UI   │    │  Server (API)   │    │   MCP Server    │    │ Agents Service  │
 ...
 └─────────────────┘                                        

---

`508-515`: **Align VITE_MCP_USE_PROXY guidance with other docs.**

This section sets `VITE_MCP_USE_PROXY=true` for LAN/Prod. Update UNIFIED-DEPLOYMENT.md accordingly, or clarify per-mode defaults here.

---

`529-534`: **Use Docker Compose V2 syntax and avoid double build.**

You can build implicitly with `up --build`; also keep CLI consistent.


```diff
-docker-compose -f docker-compose.unified.yml --profile prod build --no-cache
-docker-compose -f docker-compose.unified.yml --profile prod up -d
+docker compose -f docker-compose.unified.yml --profile prod up -d --build

---

468-473: Remove or document VITE_ARCHON_SERVER_PORT.

If this variable isn’t used anymore, drop it from Troubleshooting to avoid confusion.

---

241-247: Security note on MCP exposure.

Add a brief warning to prefer Traefik/TLS and optional auth for MCP in LAN/Prod; avoid exposing raw 8051 publicly.

Example addition:

• “In LAN/Prod, route MCP via Traefik with TLS (path /mcp or subdomain) and consider basic auth/IP allowlists.”

Also applies to: 292-298

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-06T20:04:08.138Z
Learning: Applies to .env : Require SUPABASE_URL and SUPABASE_SERVICE_KEY in .env; optional LOGFIRE_TOKEN, LOG_LEVEL, ARCHON_*_PORT variables

CLAUDE.md (1)

297-306: Conflict markers resolved correctly; section order now coherent.

"Environment vs Database Settings" followed by "Polling Architecture" matches prior guidance. Thanks for cleaning this up.

CLAUDE.md (2)

299-305: Expand the env-only list to match the unified deployment and avoid drift.

Also document CORS_ORIGINS and API_BASE_URL as env-only (these are deployment-specific and appear in the new templates and compose files).

Apply this diff:

 **Critical**: The following settings MUST come from environment variables, NOT the database:
 - `HOST` - Server hostname/domain
 - `PORT` - Server port bindings
 - `BIND_IP` - Network binding interface
+ - `CORS_ORIGINS` - Allowed browser origins (comma-separated)
+ - `API_BASE_URL` - Public base URL used by clients/proxies

---

306-306: Remove orphan heading or add content.

"## File Organization" is empty and breaks flow.

Apply this diff to remove it:

-## File Organization

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

.env.example (4)

45-52: CORS and API_BASE_URL: add LAN examples using resolved HOST.

Minor clarity: show examples that interpolate HOST to reduce mismatch.

-# Example for LAN: CORS_ORIGINS=http://localhost:3737,http://192.168.1.100:3737
+# Example for LAN: CORS_ORIGINS=http://localhost:3737,https://${HOST}:3737
@@
-# Example for LAN: API_BASE_URL=http://192.168.1.100:8181
+# Example for LAN: API_BASE_URL=https://${HOST}/api

---

69-76: Port keys order and spacing: satisfy dotenv-linter.

Reorder and trim blanks to quiet warnings.

-ARCHON_SERVER_PORT=8181
-ARCHON_MCP_PORT=8051
-ARCHON_AGENTS_PORT=8052
-ARCHON_UI_PORTP=3737
-ARCHON_DOCS_PORT=3838
+ARCHON_UI_PORT=3737
+ARCHON_SERVER_PORT=8181
+ARCHON_MCP_PORT=8051
+ARCHON_AGENTS_PORT=8052
+ARCHON_DOCS_PORT=3838

---

77-83: VITE_MCP_ ordering: keep consistent for readability/tooling.*

Put VITE_MCP_PORT before VITE_MCP_PROTOCOL to match linter hint.

-VITE_MCP_HOST=localhost
-VITE_MCP_PROTOCOL=http
-VITE_MCP_USE_PROXY=false
-VITE_MCP_PORT=8051
+VITE_MCP_HOST=localhost
+VITE_MCP_PORT=8051
+VITE_MCP_PROTOCOL=http
+VITE_MCP_USE_PROXY=false

---

96-100: PROD flag: briefly document required proxy expectation.

Add one line so users know to set HOST/CORS when enabling.

 PROD=false
+# When PROD=true, also set HOST to your domain and update CORS_ORIGINS/API_BASE_URL accordingly.

CLAUDE.md (1)

307-309: Orphan heading “File Organization” followed immediately by “Polling Architecture”.

Either add content or drop the unused heading.

-## File Organization
+## File Organization
+- <add brief bullets on where FE/BE configs live, env files, compose files>

README.md (3)

338-351: Hostname section: remind users to set BIND_IP and CORS for remote access.

Avoids common LAN misconfig.

 After changing hostname or ports:
+
+- For LAN access, set `BIND_IP=0.0.0.0` in `.env` and update `CORS_ORIGINS`/`API_BASE_URL` to your `HOST`.

---

524-536: Use “docker compose” consistently (no hyphen).

Modern Docker CLI uses docker compose. Align for consistency with earlier sections.

-docker-compose -f docker-compose.unified.yml --profile prod build --no-cache
-docker-compose -f docker-compose.unified.yml --profile prod up -d
-docker-compose -f docker-compose.unified.yml ps
+docker compose -f docker-compose.unified.yml --profile prod build --no-cache
+docker compose -f docker-compose.unified.yml --profile prod up -d
+docker compose -f docker-compose.unified.yml ps

---

494-517: LAN config snippet: add explicit BIND_IP note and clarify HTTPS.

Small tweaks to reduce setup errors.

-   BIND_IP=0.0.0.0             # Allow external access
+   BIND_IP=0.0.0.0             # Allow external access (required for LAN)
@@
-   VITE_MCP_PROTOCOL=https
+   VITE_MCP_PROTOCOL=https     # Match your reverse proxy scheme

docker-compose.yml (4)

79-99: Mirror BIND_IP comment for MCP service.

Same reasoning as server.

-      - "${BIND_IP:-127.0.0.1}:${ARCHON_MCP_PORT:-8051}:${ARCHON_MCP_PORT:-8051}"
+      # Default binds to localhost; set BIND_IP=0.0.0.0 for LAN
+      - "${BIND_IP:-127.0.0.1}:${ARCHON_MCP_PORT:-8051}:${ARCHON_MCP_PORT:-8051}"

---

132-147: Mirror BIND_IP comment for Agents service.

Keep guidance consistent.

-      - "${BIND_IP:-127.0.0.1}:${ARCHON_AGENTS_PORT:-8052}:${ARCHON_AGENTS_PORT:-8052}"
+      # Default binds to localhost; set BIND_IP=0.0.0.0 for LAN
+      - "${BIND_IP:-127.0.0.1}:${ARCHON_AGENTS_PORT:-8052}:${ARCHON_AGENTS_PORT:-8052}"

---

164-183: Frontend env: avoid redundant ARCHON_SERVER_PORT duplicates.

If both VITE_ARCHON_SERVER_PORT and ARCHON_SERVER_PORT are required, add a comment; otherwise remove one to reduce confusion.

-      - VITE_ARCHON_SERVER_PORT=${ARCHON_SERVER_PORT:-8181}
-      - ARCHON_SERVER_PORT=${ARCHON_SERVER_PORT:-8181}
+      - VITE_ARCHON_SERVER_PORT=${ARCHON_SERVER_PORT:-8181}  # FE proxy target
+      # ARCHON_SERVER_PORT already provided via above; omit if not used by FE runtime

---

19-36: Clarify BIND_IP behavior inline across all port mappings

Add an inline comment above every port mapping that uses BIND_IP: "Default binds to localhost; set BIND_IP=0.0.0.0 for LAN".

Apply this diff (repeat for the other mappings):

-      - "${BIND_IP:-127.0.0.1}:${ARCHON_SERVER_PORT:-8181}:${ARCHON_SERVER_PORT:-8181}"
+      # Default binds to localhost; set BIND_IP=0.0.0.0 for LAN
+      - "${BIND_IP:-127.0.0.1}:${ARCHON_SERVER_PORT:-8181}:${ARCHON_SERVER_PORT:-8181}"

Occurrences to update in docker-compose.yml — port mappings: lines 19, 79, 132, 169; BIND_IP env lines: 32, 96, 144.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.741Z
Learning: Applies to .env : Define required environment variables: SUPABASE_URL and SUPABASE_SERVICE_KEY

Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-12T13:47:04.535Z
Learning: Applies to .env : Ensure required environment variables are present: SUPABASE_URL and SUPABASE_SERVICE_KEY; optional LOGFIRE_TOKEN, LOG_LEVEL, ARCHON_*_PORTs

Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-13T15:53:40.741Z
Learning: Applies to .env : Optional environment variables may be set: LOGFIRE_TOKEN, LOG_LEVEL, ARCHON_SERVER_PORT, ARCHON_MCP_PORT, ARCHON_UI_PORT

archon-ui-main/src/config/api.ts (1)

24-39: Consider type refinement for port environment variable.

The port handling logic is sound, but note that import.meta.env.VITE_ARCHON_SERVER_PORT returns string | undefined. The check portEnv === null (line 32) may never match since Vite env vars are strings or undefined, not null.

If you want to be explicit about the type:

-  const portEnv = import.meta.env.VITE_ARCHON_SERVER_PORT;
+  const portEnv = import.meta.env.VITE_ARCHON_SERVER_PORT as string | undefined;
   
   // Only add port if it's actually defined and not empty
   if (portEnv === undefined) {
     // No port env var at all - use default for local dev
     console.info('[Archon] Using default ARCHON_SERVER_PORT: 8181');
     return `${protocol}//${host}:8181`;
-  } else if (portEnv === '' || portEnv === null) {
+  } else if (portEnv === '') {
     // Port explicitly set to empty - don't add port (for LAN/proxy setups)
     console.info('[Archon] No port specified - using domain only');
     return `${protocol}//${host}`;
   } else {
     // Port is defined with a value - use it
     return `${protocol}//${host}:${portEnv}`;
   }

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-19T10:31:54.292Z
Learning: Applies to python/src/server/**/*.py : Service startup, missing configuration, database connection, or critical dependency failures should crash fast with clear errors

Learnt from: CR
PR: coleam00/Archon#0
File: AGENTS.md:0-0
Timestamp: 2025-09-19T10:32:55.580Z
Learning: Applies to python/src/**/*.py : On service startup, missing configuration, DB connection failures, auth/authorization failures, critical dependency outages, or invalid/corrupting data: fail fast and bubble errors

Learnt from: Wirasm
PR: coleam00/Archon#514
File: python/src/server/utils/etag_utils.py:27-42
Timestamp: 2025-08-28T12:06:56.383Z
Learning: The ETag implementation in python/src/server/utils/etag_utils.py has known limitations with If-None-Match semantics (wildcards, multiple ETags, weak validators) that are documented in PRPs/ai_docs/ETAG_IMPLEMENTATION.md. These limitations are intentionally not addressed to keep the current implementation simple.

Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-19T10:31:54.292Z
Learning: Applies to {python/src/server/exceptions.py,python/src/server/main.py} : Define custom exceptions in exceptions.py and ensure handlers are wired in main.py

Learnt from: stevepresley
PR: coleam00/Archon#573
File: archon-ui-main/src/config/api.ts:15-25
Timestamp: 2025-09-04T16:30:05.227Z
Learning: Archon UI API config: Prefer lazy getters getApiFullUrl() and getWsUrl() over module-load constants to avoid SSR/test crashes. Avoid CommonJS exports patterns (Object.defineProperty(exports,…)) in ESM. Add typeof window guards with VITE_API_URL fallback inside getApiUrl()/getWebSocketUrl() when SSR safety is required.